home *** CD-ROM | disk | FTP | other *** search
/ Sound Fx / Sound Fx.iso / Software / UNZIPED / MPW181-5 / _SETUP.1 / porting.txt < prev    next >
Text File  |  1997-04-21  |  8KB  |  197 lines
  1. Porting notes   (04/20/97)
  2.  
  3. -----------------------------------------------------------------------
  4.  
  5. Introduction:
  6.  
  7. Starting with maplay 1.2+ 1.81, I will try to make the source as 
  8. portable as possible. If you succeed in doing a port, please
  9. e-mail the changes to me so everyone can benefit. You will be
  10. credited accordingly, and you may distribute your port freely.
  11.  
  12. I have included output classes for a few other operating systems, but 
  13. I modified them slightly, and haven't tested the modified versions. 
  14. These came either from Tobias Bading's maplay 1.2, maplay 1.3, or
  15. John Fehr.
  16.  
  17. Thanks go out to Tobias Bading for his original, portable maplay with
  18. lots of Obuffer implementations, and John Fehr for the new 
  19. command-line source and his BeOS Obuffer, and the HP-UX buffer that
  20. uses the audio server.
  21.  
  22. -----------------------------------------------------------------------
  23.  
  24. General guidelines:
  25.  
  26. You shouldn't have to delete anything, just add stuff. Try not to 
  27. mess around with too much stuff because you think it's bad style, or
  28. whatever. The less you change, the easier it will be for me to 
  29. include your source in later releases of maplay, and the harder
  30. it will be for you to use later releases of maplay. Try to keep track
  31. of your changes so you can tell me what you did.
  32.  
  33. If you can, please support Borland compilers. They gave me a free
  34. copy of BC++ 5.01, which is the reason for maplay 1.2+ getting as
  35. far as it has. Not to mention that Borland compilers are probably
  36. the best on the market.
  37.  
  38. I highly discourage using my code with ActiveX. I hate Microsoft's
  39. internet strategy, which is basically the use of its vast resources
  40. to replace anything well-written out there, like Java and Netscape,
  41. with its own proprietary crap. (For example, integrating the 
  42. operating system shell with a WWW browser -- totally ridiculous and
  43. a transparent move to make Netscape obsolete that must violate
  44. some anti-trust law). Perhaps my mind has been warped by the 
  45. disgusting  "smooth scrolling" of Internet Explorer, but I don't want 
  46. any part in what Microsoft is trying to accomplish with ActiveX.
  47.  
  48. -----------------------------------------------------------------------
  49.  
  50. How maplay works:
  51.  
  52. The general idea is that you have a main() that passes :
  53.  
  54. 1. a newly created header
  55. 2. a newly created input bitstream
  56. 3. a mutex if you want your port to be seekable or stoppable once it
  57.    has begun playing
  58. 4. various decoding options such as which channels to decode, whether
  59.    to use stdout for output, etc.
  60.  
  61. These parameters are passed through the MPEG_Args class to maplay(),
  62. which will continue to decode the stream until it is finished, or,
  63. if your port is stoppable, until the "stop" member of the MPEG_Args
  64. class is set to TRUE.
  65.  
  66. maplay() will create an operating system dependent output buffer
  67. by calling create_obuffer(), and begin decoding.
  68.  
  69. -----------------------------------------------------------------------
  70.  
  71. Here is a rough procedure of what you need to do:
  72.  
  73. 1. First you must decide what #define's to have. Here is a list of
  74. of meanings if the following #defines are on:
  75.  
  76. __WIN32__ : Port is for Win32, like Windows 95, Windows NT, or 
  77.         Win32S
  78. AIX       : Port is for IBM AIX
  79. BEOS      : Port is for BeOS
  80. HPUX      : Port is for HP-UX 
  81. IRIX      : Port is for SGI Indigo 4.0 
  82.         (ELF version of libaudio needed for 5.*, which is not 
  83.          distributed with 5.2)
  84. LINUX     : Port is for Linux
  85. NeXT      : Port is for NeXT 
  86. SPARC     : Port is for Sun SPARC
  87.  
  88. (you may add your own defines for your operating system, i.e.
  89.  FREEBSD, OS2, etc.)
  90.  
  91. If SPARC is defined, the following may be defined:
  92.  
  93. Solaris     
  94. SunOS        
  95. SunOS4_1_1  
  96. SunOS4_1_3    
  97. SunOS5+    : SunOS version 5.*
  98.  
  99. ULAW      : For SPARC, BEOS, or the file output buffer, use 8 kHz,
  100.           ulaw output
  101.  
  102. GUI       : Port is going to run in a window, so errors are reported 
  103.           to dialog boxes instead of using cerr. This must be defined
  104.         if you are going to use any of the below xxxGUI defines.
  105.  
  106. WIN32GUI  : Port is going to run in Win32 as a GUI version
  107.  
  108. (you may add your own defines for your windowing system, i.e. 
  109.  X11R6GUI, TCLTKGUI, OS2GUI, etc.)
  110.  
  111. VERBOSE   : For command-line versions, information on a stream is 
  112.           printed before it is decoded.     
  113.           
  114. SIXTEEN_BIT_COMPILER  : "int" on your compiler is a 16 bit integer,
  115.                 used for older compilers, like for DOS or
  116.                 Windows 3.1
  117.  
  118. NObool                : The "bool" type is not defined in your 
  119.                   compiler. I think this is for older, 
  120.                 non-ANSI C++ compilers.
  121.  
  122. DAMN_INTEL_BYTE_ORDER : Machine you want to port to is little endian,
  123.                     like Intel x86's or Motorola 68k's
  124.  
  125. SEEK_STOP : The decoding of the stream will be seekable or stoppable
  126.         by the user once decoding has begun. This requires the
  127.             use of threads and mutexes.
  128.  
  129. If you have one of the supported operating systems, you may be able to 
  130. do a port just by changing defines and recompiling (and probably
  131. making a Makefile)!
  132.  
  133. 2. If you are compiling on a UNIX system, you will probably want to
  134.    rename all the .cpp files with a .cc extension. This is so that
  135.    gcc will work.
  136.  
  137. 3. If you are not porting for a UNIX system or Win32, you will 
  138.    probably need to modify "ibitstr.cpp" so you can read from files.
  139.  
  140. 4. You also need to implement a output buffer to write to the audio
  141.    device. Use the virtual Obuffer class as the parent of your
  142.    new Obuffer class, and implement the functions declared in the 
  143.    Obuffer class. If you want or need to have more information passed 
  144.    to your new Obuffer, you can add members to the MPEG_Args class
  145.    (in "all.h"). Finally write a function to return a pointer to a new 
  146.    instance of _your_ Obuffer, with the prototype : 
  147.     Obuffer *create_obuffer(MPEG_Args *maplay_args);
  148.  
  149.    Include the header for your new obuffer class in "obuffer.h", and
  150.    include the implementation file (*.cc)    in "obuffer.cpp". 
  151.           
  152. 5. If you have decided to make your port seekable or stoppable, you
  153.    will have to fill in the missing functions in the OBuffer 
  154.    subclasses (except in mci_obuf.cpp). Also you will have to fill
  155.    in the type for the mutex in "all.h" and implement locking and
  156.    unlocking in "mutx_imp.h". 
  157.  
  158.    After initializing the MPEG_Args, create a new thread running
  159.    maplay(). Your interface will communicate with maplay() through
  160.    the members of the MPEG_Args class.    
  161.  
  162.    When seeking or stopping, remember to lock the mutex before
  163.    accessing or changing the volatile variables that tell maplay
  164.    to stop, seek, where to seek, etc. After you have read or 
  165.    written the appropriate variables, unlock the mutex.
  166.  
  167.    Communication with the parent process in maplay() should be filled 
  168.    in if desired.    
  169.  
  170. 6. If you want a command-line interface, make necessary any changes 
  171.    to "cmdline.cpp". These changes will probably be setting 
  172.    different members of the MPEG_Args class. If you planning on
  173.    doing a GUI version, you're pretty much on your own for that.
  174.  
  175. 7. If you are doing a GUI version, fill in the parts where an error
  176.    message would have been sent to cerr, and instead pop open a
  177.    message box with the error message. Errors are reported in
  178.    "maplay.cpp", "header.cpp", and "ibitstr.cpp".
  179.    
  180. 8. Create a Makefile if necessary. I have no idea how to make Makefiles
  181.    but I have included the Makefile from maplay 1.3b, "Makefile.old",
  182.    which should help. You can get most of the compiler flags for your 
  183.    operating system in the file "config.sh.old"; just add the necessary
  184.    defines from above.
  185.  
  186. 9. Once you are done, add yourself to the "credits.txt" file! 
  187.    Congratulations! Please send me your changes as well as your 
  188.    Makefile. Then you can distribute your port and be as famous as me 
  189.    (Jeffy Tee-Say ???who???)!!
  190.  
  191. -----------------------------------------------------------------------
  192.  
  193. So far only there are only Win32 versions of maplay 1.2+ 1.81, but as 
  194. people do ports, I'll add them here. I'd especially like to see ports 
  195. for DOS and FreeBSD, since I can run those at home.
  196.  
  197. Jeff Tsay (ctsay@pasteur.eecs.berkeley.edu)